Alice in wonderland
깃헙에서 프로젝트를 사용할 때 리드미파일의 영향도는 얼마나 된다고 보시나요? 저의 경우는 Readme파일의 완성도를 보고 프로젝트의 완성도를 가늠하는데 아주 높은 확률로 Readme 와 프로젝트의 완성도는 비슷했던 것 같습니다. 그런 의미에서 제 프로젝트를 아침부터 반성하게 되는데요
2016/10/04 Editor’s choice
noffle/art-of-readme
_art-of-readme - :love_letter: Learn the art of writing quality READMEs._github.com
어원
어원은 어디서 부터 왔을까요?
학술적으로 보면 1970년대의 특정 프로젝트까지 거슬러 올라갑니다.
PDP-10 Archive: 43,50322/read.me from decuslib10-04
_UCI LISP Random Notes The files on this FAILSAFE tape constitute the UCI LISP system. They are for the most part…_pdp-10.trailing-edge.com
또 혹자는 루이스 캐롤의 ‘이상한 나라의 앨리스’에서 비롯되었다고 합니다. 물약과 케이크에 “Drink Me” 그리고 “Eat Me” 라고 적혀 있었다고 하는군요.
흥미롭네요.
뭐 어쨌거나 이 README 파일은 “사용자가 작업하기 전에 읽어봐야 되는 중요한 정보”로써 사용되고 있습니다.
저자를 위해, 사용자를 위해
이 프로젝트는 README를 작성하는 사람과 읽는 사람 모두에게 필요하므로 작성되었다고 하는데 저 또한 동의합니다.
작성자에게는 6개월 정도가 지나면 새로울 것이므로 남겨놓는 유산으로써의미가 있고 사용자에게는 의존성을 파악하고 프로젝트를 사용하는데에 도움이 됩니다
프로답게 쓰는 README
읽는 사람을 생각해서 작성한다면 기본적으로 다음을 고려해야 하는데요
- 이게 무엇인지(what)
- 동작할 때 어떻게 보이는지(what it looks like in action)
- 어떻게 사용하는 지(how)
- 관련된 상세(details)
등을 고려해야 한다고 합니다.
핵심 섹션
기본적인 골격은 다음과 같습니다.
- 이름 — 이름이 무엇보다 중요합니다. react-router라는 이름은 이름만으로 무슨 프로젝트인지 알 수 있으니까요
- 한줄 요약 — 이름이 중요한 것 처럼 한줄로 이 프로젝트의 정체성을 나타내 주는 것이 좋습니다
- 사용법 — API 문서로 바로 가는 것보다 사용법을 설명해 주는 것이 좋습니다.
- API — 이름, 설명, 사용법이 보여지고 나면 API의 상세함이 프로젝트의 품격을 결정합니다
- 설치방법 — 자, 이제 전체를 읽어봤으니 어떻게 설치할 지를 알 수 있어야 사용자가 마지막 결정을할 수 있습니다.
- 라이센스 — 이 프로젝트를 내가 사용할 수 있는지에 대한 중요한 정보를 담고 있죠.
이후도 중요한 내용들을 많이 담고 있지만, 인상깊게 읽었던 부분은 사람들의 시간을 고려해라, 백그라운드 섹션을 할애해라. 공격적으로 링크를 걸고 arguments와 parameter를자세하게 적어라. 등등이 기억에 남는군요.
그리고, 이 프로젝트의 저자는 Node 생태계를 위해 이 글을 작성했는데, Perl 의 개발자들이 작성했던 좋은 예들을 설명하고 있습니다.
이런 좋은 프로젝트를 아침부터 만난다는 것은 즐거운 일이군요~
By Keen Dev on October 3, 2016.
Exported from Medium on May 31, 2017.